Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Usage docs #68

Merged
merged 11 commits into from
Jun 2, 2020
Merged

Usage docs #68

merged 11 commits into from
Jun 2, 2020

Conversation

brettch
Copy link
Member

@brettch brettch commented May 27, 2020

Background

With Michal breathing some life into the Osmosis project again it's great to see the recent PR activity.

In my years maintaining the project, there were a number of things that made reviewing and incorporating PRs tedious from my side. I made many little changes over time to make this easier, not least of which were the docker-based build/tests and Travis CI to allow anybody to verify their changes.

But one area that was always a pain was keeping the documentation up to date. Contributors were hesitant to make changes to the wiki until changes were approved and I often found it easier to make the changes myself than to chase people. A number of the current pending PRs will require documentation changes.

I think it would be easier to maintain if the docs were maintained alongside the code itself in Git. Putting the docs on the OSM wiki made sense at the time, but times and tooling have changed.

Change

I have done an automatic conversion of the Mediawiki markup to Asciidoc

I initially tried Markdown but the lack of support for auto-generating a table of contents makes it far from ideal. Asciidoc syntax does support a table of contents.

The doc is currently one huge file (same as the wiki page) but I think it's easier to quickly find what you're looking for that way. It can be split into multiple files if necessary (I'd suggest one per module/plugin).

I've also done some relatively minor cleanups to the main README, the main one being moving the Development docs into a separate file.

@migurski
Copy link
Collaborator

migurski commented Jun 2, 2020

Thanks Brett!

@migurski migurski merged commit b2ce686 into openstreetmap:master Jun 2, 2020
@brettch brettch deleted the usage-docs branch June 3, 2020 09:58
@brettch
Copy link
Member Author

brettch commented Jun 3, 2020

Thanks for merging.

Unfortunately I appear to have broken the detailed usage table of contents in my last commit. I've raised a new (fairly trivial) PR #69 to fix it.

@brettch brettch restored the usage-docs branch March 20, 2021 03:54
@brettch brettch deleted the usage-docs branch March 20, 2021 03:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants